Made all the suggested the changes and squashed to a single commit.

Why does this useful description not appear on FAQ? It was merged, but FAQ on master has nothing like that now, made me struggled really hard to understand that dep add a ^ in front of version = "X.Y.Z".

Through 3 months of using dep, I have some opinions about version constraint. Firstly this is a really confusing and implicit feature, I haven't seen any other tools that implies version = "X.Y.Z" to be equal to version = "^X.Y.Z". Version management is something very serious, talking about this I always refer to the quote "explicit is better than implicit", but if the authors of dep decided to do that with your concern, that's fine, but please notify the users whatever way that could be more significant than hide in some PR descriptions (#644). There's no straightforward words talk about this feature in FAQ, which is actually the only docs of dep (this is also a sad thing, no formal docs 😞). As user, I would always be tolerant if any mistakes happens, or new feature breaks backward compatibility, those are all OK, because dep is still growing like a child. But this process could be made more friendly, like you can make releases, add changelog to what happens in each version change, also a simple specification could be written for Gopkg.toml if you don't have time to do full documentation (I just noticed the spec exists while writing this). I mean dep is a tool about code management, how can it win user's trust if it can't manage itself decently?

I really appreciate your works on dep, dep is a great tool that gives the community one last standard to rule them all, hope it can get better and better.

@reorx sorry for the trouble. The version operations and detailed docs were recently moved into docs/Gopkg.toml.md as that seemed to be a better place to keep all the Gopkg.toml related docs and the generated Gopkg.toml links to the same docs for more details.

@reorx sorry, meant to respond to this earlier. let me go point by point:

Firstly this is a really confusing and implicit feature [...] Version management is something very serious, talking about this I always refer to the quote "explicit is better than implicit", but if the authors of dep decided to do that with your concern, that's fine

Yes, we know it can be confusing. And I think it's fair to say we take the problem of version management quite seriously. I explained a bit about the motivation behind the design choice in #929.

I haven't seen any other tools that implies version = "X.Y.Z" to be equal to version = "^X.Y.Z"

Cargo does.

but please notify the users whatever way that could be more significant than hide in some PR descriptions (#644).

Providing communication channels is, of course, a difficult problem in general.

In the case of #644, we were very clear and public about the file format not being stable, and that committing/building CI around it was a bad idea, and you should only do so with the knowledge that it would break later. It was the first thing (after a couple-sentence summary) in the README. And, in the regular updates I try to be careful about announcing things like this - indeed, it was the very first sentence of the relevant update.

As user, I would always be tolerant if any mistakes happens, or new feature breaks backward compatibility, those are all OK, because dep is still growing like a child.

As noted in the above-linked status update post, and the README ever since we merged #649, we now make the guarantee that backwards-incompatible changes will not happen to Gopkg.toml and Gopkg.lock.

But this process could be made more friendly, like you can make releases

We now have three releases. We held off on making them until after the config file format was stable, specifically to avoid even giving the impression of stability. The first one was made as soon as we became stable.

We do, however, lack a changelog on these releases. That's something I'd definitely like to do better, but I'm really starting to face a time crunch with all this. @darkowlzz has proposed introducing a system for structuring commit messages that can then generate a changelog; that might help a lot. Or (non-exclusively), a volunteer would also be tremendously helpful. Meanwhile, though, the aforementioned dep status updates typically include a list of significant changes that have come in; these could suffice.

There's no straightforward words talk about this feature in FAQ, which is actually the only docs of dep (this is also a sad thing, no formal docs 😞).

Yes, I've been pained by the lack of formal docs for quite some time now. Our FAQ has grown considerably, and does answer many questions, as do the Gopkg.toml docs that @darkowlzz mentioned. But we do lack end-to-end workflow guides. Other suggestions for docs are welcome - even more welcome would be volunteering to work on writing some 😄

I mean dep is a tool about code management, how can it win user's trust if it can't manage itself decently?

I think we've won a lot of users' trust so far, but there's certainly still a lot more work to do. The actionable items I'm able to take from your points are "changelogs on releases" and "supplement FAQ with guides, and maybe write more on major topic areas". A third might be "make the README better so that people can better find their way to appropriate resources," however, some of your concerns seem like ones that should've been addressed by reading the README.

I really appreciate your works on dep, dep is a great tool that gives the community one last standard to rule them all, hope it can get better and better.

thank you - so do we!